RCS Campaign APIs
The RCS Campaign APIs enable businesses to create and launch rich, interactive RCS campaigns. These APIs support advanced messaging features including rich cards, carousels, and interactive buttons.
Prerequisites
- RCS Business Account: Active RCS Business Messaging account with verified brand
- Msgkart Account: An active Msgkart account with API Key
- Approved Rich Cards: Pre-approved RCS message templates with rich media
Launch RCS Campaign with Form Data
Creates and launches a new RCS campaign with rich media content.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Request headers
"x-api-key": "<API KEY>"
Form Data
Use multipart/form-data to upload the CSV file along with the request body.
file: {{csvFile}}
body: JSON
{
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"template": {
"name": "{{tempalteName}}",
"id": "{{tempalteId}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{ "type": "text", "value": "${name}" },
{ "type": "text", "value": "${phone}" },
{ "type": "text", "value": "${language}" },
{ "type": "text", "value": "${businesssubscriberid}" },
{ "type": "text", "value": "${name}" },
{ "type": "text", "value": "${language}" },
{ "type": "text", "value": "${phone}" }
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
}
]
}
]
},
"channelType": "rcs"
}
Launch RCS Campaign on an Uploaded List
Launches an RCS campaign targeting contacts from an uploaded CSV file with rich interactive content.
Request Syntax
POST api/v2/promotion/{{msgkartId}}/template/launch?name={{nameOfTargetList}}
Request headers
"x-api-key": "<API KEY>"
Request Body
{
"name": "{{promotionName}}",
"promotionType": "IMMEDIATE",
"promotionBase": "TEMPLATE",
"promotionTemplateType": "TEMPLATE",
"template": {
"name": "{{tempalteName}}",
"id": "{{tempalteId}}",
"language": "{{templateLanguage}}",
"components": [
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "BODY",
"variables": [
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${phone}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${businesssubscriberid}"
},
{
"type": "text",
"value": "${name}"
},
{
"type": "text",
"value": "${language}"
},
{
"type": "text",
"value": "${phone}"
}
]
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}"
}
}
]
}
]
}
]
},
"channelType": "rcs"
}
Properties
| Property | Description | Sample |
|---|---|---|
campaignName | Name of the RCS campaign | Black Friday Sale |
messageType | Type of RCS message | rich_card, carousel, standalone |
content | Rich content object with title, description, and media | See request body |
title | Title of the rich card | Exclusive Deals |
description | Description text for the card | Get up to 70% off |
mediaUrl | URL of the media (image/video) | https://example.com/img.jpg |
mediaHeight | Height of the media | SHORT, MEDIUM, TALL |
suggestions | Interactive action buttons | Array of suggestion objects |
uploadedListId | ID of the uploaded contact list | list_rcs_456 |
targetAudience | Target audience segment | all, premium, engaged |
scheduledTime | Scheduled launch time (ISO 8601 format) | 2024-11-29T00:00:00Z |
Get Promotions
Retrieves all RCS campaigns for a specific business account.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}?channel=rcs
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Response Body
{
"promotions": [
{
"promotionId": "{{promotionId}}",
"businessId": "{{businessId}}",
"msgkartId": "{{msgkartId}}",
"name": "{{promotionName}}",
"channelType": "rcs",
"status": "Completed",
"createdBy": null,
"promotionType": "IMMEDIATE",
"targetSource": "CSV",
"targetType": "{{targetType}}",
"flowId": null,
"flowName": null,
"promotionBase": null,
"attributionWindow": 0,
"promotionEndTime": 1765385829,
"createdDate": 1765385766
}
]
}
Get Promotion Statistics Report
Retrieves detailed statistics and analytics for a specific RCS campaign.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/statistics/{{promotionId}}/report?channel=rcs
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Response Body (CSV Format)
Name,Phone,Status,Timestamp,Error,FlowId,FlowName,RetryCount,TemplateName,Language
{{name}},{{phone}},{{status}},{{timestamp}},{{error}},{{flowId}},{{flowName}},{{retryCount}},{{templateName}},{{language}}
Get Promotion Stats
Retrieves real-time statistics for a specific RCS campaign.
Request Syntax
GET /api/v2/promotion/{{msgkartId}}/{{promotionId}}/stats?channel=rcs
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for this endpoint) |
Response Body
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"statsReport": [
{
"attempted": 8,
"failed": 2,
"sent": 0,
"delivered": 0,
"read": 6,
"interacted": 0,
"optout": 0,
"promotionRetryNumber": 0
}
]
}
Cancel RCS Campaign
This action is allowed only during the campaign preparation phase. Once cancelled, the campaign will not exist and cannot be resumed.
Request Syntax
PATCH /api/v2/promotion/{{msgkartId}}/{{promotionId}}?channel=rcs
Request headers
"x-api-key": "<API KEY>"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
msgkartId | string | Yes | Your Msgkart business ID |
promotionId | string | Yes | ID of the promotion to update |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | Channel type (use rcs for RCS) |
Request Body
{
"type": "status",
"status": "Stopped"
}
Status Values
| Value | Description |
|---|---|
Stopped | Temporarily stop the promotion (can be resumed) |
Cancelled | Permanently cancel the promotion (cannot be resumed) |
Response Body
{
"promotionId": "{{promotionId}}",
"businessId": "{{businessId}}",
"msgkartId": "{{msgkartId}}",
"name": "{{promotionName}}",
"targetListId": "{{targetListId}}",
"targetListName": "{{targetListName}}",
"phoneNumberId": "{{phoneNumberId}}",
"template": {
"name": "{{templateName}}",
"id": "{{templateId}}",
"language": "{{language}}",
"category": "{{category}}",
"components": [
{
"variables": [
{
"type": "text",
"value": "{{name}}"
}
],
"type": "BODY"
},
{
"type": "HEADER",
"format": "IMAGE",
"media": {
"mediaUrl": "{{mediaUrl}}",
"fileName": "{{fileName}}"
}
}
]
},
"createdDate": 1765777610,
"startTime": 0,
"mostRecentStartTime": 0,
"status": "Cancelled",
"createdBy": "a599947d-bc5c-4b45-b93c-5a318e2e2243",
"promotionType": "IMMEDIATE",
"scheduleTime": "0",
"targetSource": "CSV",
"tagSearchCriteria": "ANY",
"retryPromotion": true,
"maxRetries": 3,
"retriesLeft": 3,
"channelType": "rcs",
"batchSize": 0,
"batchTimer": 0,
"staggered": false,
"subscriberLimitPerGroup": 0,
"attributionWindow": 0,
"promotionBase": "TEMPLATE",
"promotionEndTime": 1765777679,
"callCampaign": false,
"utilityTemplateIndex": 0,
"stopOnCategoryUpdate": false
}